Working With Custom Hooks: OnAssetCategorizationChange
Taxonomy categories can be applied to content items in the CMS and are primarily used for querying, filtering, and sorting content on a website. We look at how this custom hook can be used to set paramaters around how and when a category is changed on an asset.
In previous articles, we introduced the taxonomy system in Ingeniux CMS. Located in the Administration Section of the platform, the Taxonomy Manager is where users create and manage a hierarchical structure of categories that are then applied to pages, components, and assets.
In this article, we’ll explore the OnAssetCategorizationChange custom hook, which would trigger whenever a category is added or removed to an asset in the Asset Tree.
To change the categorization of an asset, it must be checked out and assigned to the user attempting to make the change.
Assets are not categorized as often as pages or components. An asset might get categorized for filtering purposes when returned as a result in a search query or to pare down the results of an asset navigation that indexes a folder of content.
How To Trigger the Hook
This method is triggered through the following actions:
- Adding or removing a category on an asset through the Categorize tab in the Asset area and saving.
- Adding or removing a category on an asset through the Associations tab of a category in Administration > Taxonomy.
- Initiating a script that adds or removes a category from an asset.
When to Use This Custom Hook
CMS administrators might be interested in using this custom hook to:
- Limit or block the removal or duplication of high-level categories.
- Notify content owners when categorization changes have been made to their content.
- Disallow publishing until management approval is complete.
Considerations
Take care when using this hook to add or remove other categories, as an infinite loop could be triggered.
If an error is thrown after a category is added or removed, the user will have to undo their actions prior to navigating way from the Categorize tab, since leaving the tab will initiative a save.
Example
Add the ID of the asset to the external ID field in the category for tracking
In this example, the custom hook connects an asset to a category by using the External ID field on the category as a storage device, enabling the retrieval of the asset to be used as content and displayed on the page when a category is applied to that page. This could be used to display an icon, banner, or similar content on all pages that share a category.
The code checks the existence of an asset and operations related to associating the asset with a category. The specific actions taken depend on the value of the "action" parameter, which is an enum of which action was taken: associating (0) or unassociating (1) with the category.
This example code checks if the asset is not null using the condition. If the condition is true, the code block within the curly braces will be executed.
Inside the if statement, there is another conditional check using the variable "action". If "action" is equal to 0, the code block within the next set of curly braces will be executed. Otherwise, the code block within the "else" block will be executed.
Within the first conditional block, there is an additional check using the method "string.IsNullOrWhiteSpace(category.ExternalID)" to determine if the variable "category.ExternalID" is null, empty, or contains only whitespace. If it is not null or empty, the code appends the value of the External ID attribute on the category with a comma and the value of the ID of the asset. If it is null or empty, the code assigns the value of the asset ID to the External ID attribute.
In the second conditional block (the "else" block), the code is meant to unassociate a content item with a category. It first checks if External ID is not null or empty. If it is not, the code replaces occurrences of the asset ID followed by a comma (",") with an empty string, and also replaces occurrences of just the asset ID with an empty string.
if (asset != null)
{
if (action == 0)
{
if (!string.IsNullOrWhiteSpace(category.ExternalID))
{
category.ExternalID = category.ExternalID + "," + asset.Id;
}
else
{
category.ExternalID = asset.Id;
}
}
else
{
if (!string.IsNullOrWhiteSpace(category.ExternalID))
{
category.ExternalID = category.ExternalID.Replace(asset.Id + ",", "").Replace(asset.Id, "");
}
}
}
Ways to Extend the Functionality Further
There are several extensions and enhancements that could be made to improve the functionality and efficiency of the code:
- Error handling: Add appropriate error handling mechanisms, such as try-catch blocks, to handle any potential exceptions that may occur during execution. This will help in identifying and gracefully handling errors, preventing crashes or unexpected behavior.
- Parameter validation: Validate the inputs to ensure they are not null before executing the code. This will prevent potential null reference exceptions and improve the reliability of the code.
- Refactoring: The strings could be split on the comma to avoid ambiguity.
There are no comments yet.